.\" Copyright (C) 2008 Canonical Ltd.
.\"
.\" Author: Steve Langasek <steve.langasek@canonical.com>
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of version 3 of the GNU General Public License as
.\" published by the Free Software Foundation.
.\"
.\" .\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301,
.\" USA.
.TH "PAM\-AUTH\-UPDATE" "8" "08/23/2008" "Debian"
.SH NAME
pam\-auth\-update - manage PAM configuration using packaged profiles
.SH SYNOPSIS
.B pam\-auth\-update
.RB [ \-\-package " [" \-\-remove
.IR profile " [" profile\fR... "]]]"
.RB [ \-\-force ]
.RB [ \-\-enable
.IR profile " [" profile\fR... "]]"
.RB [ \-\-disable
.IR profile " [" profile\fR... "]]"
.SH DESCRIPTION
.I pam\-auth\-update
is a utility that permits configuring the central authentication policy
for the system using pre-defined profiles as supplied by PAM module
packages.
Profiles shipped in the 
.I /usr/share/pam\-configs/
directory specify the modules, with options, to enable; the preferred
ordering with respect to other profiles; and whether a profile should be
enabled by default.
Packages providing PAM modules register their profiles at install time
by calling
.BR "pam\-auth\-update \-\-package" .
Selection of profiles is done using the standard debconf interface.
The profile selection question will be asked at `medium' priority when
packages are added or removed, so no user interaction is required by
default.
Users may invoke
.B pam\-auth\-update
directly to change their authentication configuration.
.PP
The script makes every effort to respect local changes to
.IR "/etc/pam.d/common-*".
Local modifications to the list of module options will be preserved, and
additions of modules within the managed portion of the stack will cause
.B pam\-auth\-update
to treat the config files as locally modified and not make further
changes to the config files unless given the
.B \-\-force
option.
.PP
If the user specifies that
.B pam\-auth\-update
should override local configuration changes, the locally-modified files
will be saved in
.I /etc/pam.d/
with a suffix of
.IR "\.pam\-old" .
.SH OPTIONS
.TP
.B \-\-package
Indicate that the caller is a package maintainer script; lowers the
priority of debconf questions to `medium' so that the user is not
prompted by default.
.TP
.B \-\-disable \fIprofile \fR[\fIprofile\fR...]
Disable the specified profiles in system configuration.  This can be used from system administration scripts to disable profiles.
.TP
.B \-\-enable \fIprofile \fR[\fIprofile\fR...]
Enable the specified profiles in system configuration. This is used to
enable profiles that are not on by default.
.TP
.B \-\-remove \fIprofile \fR[\fIprofile\fR...]
Remove the specified profiles from the system configuration.
.B pam\-auth\-update \-\-remove
should be used to remove profiles from the configuration before the
modules they reference are removed from disk, to ensure that PAM is in a
consistent and usable state at all times during package upgrades or
removals.
.TP
.B \-\-force
Overwrite the current PAM configuration, without prompting.
This option
.B must not
be used by package maintainer scripts; it is intended for use by
administrators only.
.SH FILES
.PP
.I /etc/pam.d/common\-*
.RS 4
Global configuration of PAM, affecting all installed services.
.RE
.PP
.I /usr/share/pam\-configs/
.RS 4
Package-supplied authentication profiles.
.RE
.SH AUTHOR
Steve Langasek <steve.langasek@canonical.com>
.SH COPYRIGHT
Copyright (C) 2008 Canonical Ltd.
.SH "SEE ALSO"
PAM(7), pam.d(5), debconf(7)
